﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">NavigationService</title>
  <keywords>
    <keyword translate="true">INavigationService</keyword>
    <keyword translate="true">MVVM</keyword>
    <keyword translate="true">NavigationService</keyword>
    <keyword translate="true">Services</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">NavigationService</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Services_INavigationService" styleclass="Normal" translate="true">INavigationService</link><text styleclass="Normal" translate="true"> allows a developer to navigate to other pages inside an application using view models only.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">All pages will have to be registered manually or following the right naming convention.</text></para>
    <para styleclass="Normal"><table styleclass="Default" rowcount="8" colcount="2">
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" style="font-weight:bold;" translate="true">Feature</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><text styleclass="Normal (list)" style="font-weight:bold;" translate="true">Supported</text></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">WPF</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Silverlight 4</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Silverlight 5</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows Phone 7 Mango</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows Phone 8</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="notsupported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows RT</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="notsupported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Test/emulation service</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
    </table></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">For WPF and Silverlight, the pages must inherit from </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_Windows_Controls_Page" styleclass="Normal" translate="true">Page</link><text styleclass="Normal" translate="true">. For WP7, the pages must inherit from </text><text styleclass="Normal" style="font-style:italic;" translate="true">PhoneApplicationPage</text><text styleclass="Normal" translate="true">. In WPF, the parameters are of type </text><text styleclass="Normal" style="font-style:italic;" translate="true">Dictionary&lt;string, object&gt;</text><text styleclass="Normal" translate="true">, in Silverlight and WP7, the arguments are of type </text><text styleclass="Normal" style="font-style:italic;" translate="true">Dictionary&lt;string, string&gt;</text><text styleclass="Normal" translate="true">.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Closing an application</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is possible to close an application using the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.CloseApplication();</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Preventing an application to be closed</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To prevent an application to be closed, one can subscribe to the </text><text styleclass="Normal" style="font-style:italic;" translate="true">ApplicationClosing</text><text styleclass="Normal" translate="true"> event:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.ApplicationClosing += (sender, e) =&gt;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">    e.Cancel = true;</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">};</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Navigating to a new view</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To navigate to a new page, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> </text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.Navigate&lt;EmployeeViewModel&gt;();</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Navigating with parameters</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is very easy to navigate to a new page with parameters. Use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var parameters = </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true"> Dictionary&lt;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">, </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">object</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">parameters.Add(&quot;id&quot;, employee.EmployeeID);</text><br/><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var navigationService = GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.Navigate&lt;EmployeeViewModel&gt;(parameters);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Navigating back and forward</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The service also supports navigating back and forward:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var navigationService = GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.GoBack(); </text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// navigates to the previous page, obviously</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.GoForward(); </text><text styleclass="Code Example" style="font-weight:normal; font-style:italic; color:#800000;" translate="true">// navigates to the next page, obviously</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Navigating to a custom Uri</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To navigate to a custom uri without a view model type, use the following code. Of course it&apos;s also possible to pass parameters using the right method overload.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var navigationService = GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.Navigate(&quot;/UI/Pages/EmployeePage.xaml&quot;);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Registering custom views</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To register custom views, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var navigationService = GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.Register(</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(EmployeeViewModel), </text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">typeof</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">(EmployeeDetailsPage));</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Using naming conventions to find pages</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">If you use a consistent naming convention for views, it is possible to apply this naming convention to the service. This saves a lot of custom registration. When a page is not registered, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IUIVisualizerService_Show_2_871b697f" styleclass="Normal" translate="true">Show</link><text styleclass="Normal" translate="true"> method will try to find the view using the naming convention.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To add a naming convention, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var navigationService = GetService&lt;INavigationService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">navigationService.NamingConventions.Add(</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000080;" translate="true">string</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">.Format(&quot;/Views/My{0}View&quot;, NamingConvention.ViewModelName));</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The above naming convention will use the following combination:</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Input: </text><text styleclass="Normal" style="font-style:italic;" translate="true">MyAssembly.UI.ViewModels.EmployeeViewModel</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Output: </text><text styleclass="Normal" style="font-style:italic;" translate="true">MyAssembly.UI.Windows.EmployeeWindow&apos;</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">By default, the following naming conventions will be used:</text></para>
    <list id="1" type="ul" listtype="bullet" formatstring="·" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Views/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Views/[VM]View.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Views/[VM]Control.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Views/[VM]Page.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Views/[VM]Window.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Controls/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Controls/[VM]Control.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Pages/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Pages/[VM]Page.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Windows/[VM].xaml </text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/Windows/[VM]Window.xaml </text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Views/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Views/[VM]View.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Views/[VM]Control.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Views/[VM]Page.xaml </text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Views/[VM]Window.xaml </text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Controls/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Controls/[VM]Control.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Pages/[VM].xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Pages/[VM]Page.xaml</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Windows/[VM].xaml </text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">/UI/Windows/[VM]Window.xaml </text></li>
    </list>
  </body>
</topic>
